home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / PTMID3.ZIP / PTMID.DOC < prev    next >
Text File  |  1994-07-18  |  17KB  |  351 lines

  1. NAME
  2.  
  3.      ptmid - Creates Protracker MOD files or Multitracker MTM files 
  4.              from General MIDI files (ver 0.3)
  5.  
  6.  
  7. SYNOPSIS
  8.  
  9.      ptmid [-cFile] [-dChannel] [-fFrac] [-q] [-s] infile[.mid]
  10.           [outfile[.mod]]
  11.  
  12.  
  13. DESCRIPTION
  14.  
  15.      Ptmid will take either standard MIDI format 0 or format 1 files and
  16.      convert them into various Tracker-type files. MIDI files are
  17.      industry standard, but need some sort of sequencer to be played, as
  18.      there can be near infinite simultaneous notes (though about 20 is a
  19.      standard maximum). Protracker files are 4 channel (though 6, 8, and
  20.      just about any other variety is supported) files, but have a bank
  21.      of digitized instruments included, so reasonable quality sound is
  22.      produced given limited hardware. Multitracker files are similar,
  23.      and support upto 32 simultaneous notes. Both Protracker and
  24.      Multitracker files are referred to as Tracker files in this
  25.      document.
  26.  
  27.      The differences between MIDI (extension .mid) and Tracker
  28.      (extension .mod or .mtm) formats are more than superficial, and a
  29.      fair bit of information is needed to be able perform the conversion
  30.      - most of this is held in the configuration file: ptmid.cfg
  31.  
  32.      The format of ptmid.cfg is fairly simple: Any line beginning with a
  33.      hash (#) is ignored, other lines contain configuration info. The
  34.      first word on a line (called a tag) specifies what sort of
  35.      information (and sometimes only one word is needed), anything
  36.      following this word is used as supplementary information and
  37.      depends of the sort of option specified by the first word. 
  38.  
  39.      One type of word needs a little explaining: pitch. A pitch, when
  40.      used in the configuration file, is a character string in the format
  41.      of: C2, C#2, D2, D#2, E2, F2, F#2, G2, G#2, A2, A#2, B2 (that was a
  42.      whole octave beginning with middle C). Other octaves can be used in
  43.      place of 2, eg. D#2, A-1, etc.
  44.  
  45.      Here are a list of the tags permissible in the configuration file:
  46.  
  47.           spath: The word following this tag is the name of the
  48.           directory that any subsequent samples will be found in. It
  49.           must end in a trailing slash, and be located in the file
  50.           before any line using the tags: def, xx, or dxx.
  51.  
  52.           def, or xx (where xx is a number): These options supply
  53.           information on what samples (digitized instruments) should be
  54.           allocated to what MIDI instrument numbers. "def" is the
  55.           default non-percussion instrument, and must always be
  56.           specified. "xx" is a specific MIDI instrument. After the tag
  57.           are the filenames of the samples that can be used to represent
  58.           the instrument (if multiple filenames are used, then the one
  59.           sampled closest to the desired pitch for a note is chosen from
  60.           the list). If an allocation is not present for some particular
  61.           instrument, then the default instrument is used instead. A
  62.           shortcut is to put a quotes (") mark instead of a list of
  63.           filenames. This tells Ptmid that that instrument is identical
  64.           to the last one specified.
  65.  
  66.           dxx (where xx is a number): This is similar to the above tag,
  67.           but applies to percussion samples. The first word following
  68.           the tag is the filename of the sample to associate with the
  69.           appropriate MIDI percussion instrument (only one filename can
  70.           be used). If there is another word following this, it is the
  71.           pitch to play the sample at when used in the Tracker file.
  72.           There is no default sample for non-specified percussion
  73.           instruments, as these are simply not played.
  74.  
  75.           sample: The information following this tag tells Ptmid crucial
  76.           information about a sample. Samples can either be in .SMP
  77.           format (this is the default, and corresponds to headerless, 8
  78.           bit signed data), .WAV format, or .VOC format. The first word
  79.           following the tag is the filename of the sample which is to be
  80.           defined (and must correspond exactly to the filename of this
  81.           sample used elsewhere in the ptmid.cfg file). The next word is
  82.           the pitch of the sample when it's played (at 8287 Hz for .SMP
  83.           files, or the normal rate for .WAV or .VOC files). Optionally,
  84.           it can then be followed by a loop-start offset and a loop-
  85.           length (in that order), specified in words (1 word = 2 bytes).
  86.           After a sample is played it will stop if no loop information
  87.           is given, otherwise it will start looping at the loop-start
  88.           address and continue for the length of the loop-length
  89.           (looping continues indefinitely). A "sample" must be present
  90.           for EVERY filename given in one of the above options (def, xx,
  91.           or dxx).
  92.  
  93.           drumch: The percussion channel is assumed to be 10, but some
  94.           MIDI devices assume it is elsewhere, and so Ptmid must know
  95.           what channel it will be to perform a correct conversion.
  96.           Following the tag name is a number which is the percussion
  97.           channel. Common values are 10 and 16.
  98.  
  99.           fract: Ptmid quantizes (that is, groups notes to the closest
  100.           note) MIDI files duration conversion, and so must know what
  101.           the smallest type of note is. Following the tag name is a
  102.           number (possibly with a suffix of "t") which represents a type
  103.           of note - this is the quantize fraction. Valid fractions are
  104.           of the form: 4, 4t, 8, 8t, 16, 16t, etc. where 4 means a
  105.           quarter note (crotchet), 4t means a triplet, 8 means an
  106.           eighth-note (quaver), 8t means quaver-triplets, etc. It
  107.           usually can't hurt to give a smaller note (larger value),
  108.           though it uses up more memory, but the critical part is
  109.           knowing if a triplet note is needed. If not specified, the
  110.           fraction is assumed to be 16. This option can be overridden
  111.           with the similar option specified on the command line.
  112.  
  113.           modfmt: This tag chooses the type of Tracker file to produce.
  114.           If the word following the tag name is "1", then Protracker
  115.           .mod files are produced (this is the default). If the word is
  116.           "2", then Multitracker .mtm files are produced.
  117.  
  118.           maxchan: Following this tag is a number representing the
  119.           number of channels to have in the final Tracker file. It will
  120.           default to 4, and can have values upto 32. If creating a
  121.           Protracker file, putting values other than 4 may result in a
  122.           .mod file that cannot be played by your Tracker program,
  123.           although 6 and 8 are common too.
  124.  
  125.           extend: If this tag is present, then an extended range of
  126.           notes is allowed during conversion. Usually there is a 3
  127.           octave range, but since MIDI allows a 9 octave range
  128.           converted files can sound wrong. With an extended range, 5
  129.           octaves are supported, but you need special trackers for this
  130.           (the tracker DMP is one example). The best solution for this
  131.           problem is to use multiple samples, each of which is digitized
  132.           an octave apart, and specify all of them for an instrument.
  133.  
  134.           rgmode: There are 3 things Ptmid can do if despite using
  135.           "extend", a note is out-of-range. These things can be chosen
  136.           by specifying a number following this tag:
  137.                0 - This rounds a note to the nearest pitch (the default)
  138.                1 - Drop the note altogether
  139.                2 - Transpose the note by octaves until it's in range
  140.           Mode number 2 sounds the best, but it can generate melodies
  141.           that don't sound like the original, and is not the default.
  142.  
  143.           nocopy: This tag will stop copyrighted MIDI files being
  144.           converted if it is present. Since MIDI files support a
  145.           copyright notice as part of their official format, I thought
  146.           that this would be a good option for the fascist-minded.
  147.  
  148.      Options in the configuration file may be given in any order, and
  149.      are all optional except for "def" and "sample".
  150.      DMP is written by Otto Crons (no relation :).
  151.  
  152.      How Ptmid works. Well.. It goes through the following steps:
  153.      1)   Read the configuration file and check each sample specified
  154.           (this is necessary so as to extract the sample-frequency of
  155.           samples in .WAV or .VOC format).
  156.      2)   Read in the entire MIDI file (except effects such as pitch
  157.           bend, mod wheel, etc.) into memory.
  158.      3)   Scan the tune and allocate samples to each note, convert the
  159.           volumes etc.
  160.      4)   Write the tune to disk as a Tracker file. If there are more
  161.           notes than channels at any particular time, it picks what it
  162.           guesses to be shorter notes rather than longer notes. The
  163.           reason behind this is that shorter notes allow more notes to
  164.           come later, freeing up channels sooner.. okay, so it's not a
  165.           very good reason, but it tends to sound better than simply
  166.           dropping notes.
  167.  
  168.      I originally wanted to do "channel pruning" before the writing
  169.      stage occurred, but yes I'm slack and wanted to get a working copy
  170.      released. And now with ver 0.3, I have modified it extensively, and
  171.      still can't be bothered. Anyway, this means there is a bit of
  172.      inelegancy: samples may be allocated to notes, but those notes are
  173.      pruned later on and are never played, leaving redundant samples.
  174.      Other things I want to add are: compression (ie. identification of
  175.      common patterns and re-using them), MIDI effects, volume decay of
  176.      samples, and calculation of default volumes (at the mo they are
  177.      just set to 64).
  178.  
  179.  
  180. OPTIONS
  181.  
  182.      cFile     "File" is the filename of the configuration file. If not
  183.                given will default to "ptmid.cfg". See above for format
  184.                of the configuration file.
  185.  
  186.      dChannel  "Channel" is a number from 1 to 16. This is the channel
  187.                used for percussion instruments. See "drumch" option
  188.                above.
  189.  
  190.      fFrac     "Frac" is a quantize fraction. It can take values of the
  191.                form: 4, 4t, 8, 8t, etc. See the "fract" option above,
  192.                which this option overrides.
  193.  
  194.      q         Enables quiet-mode. Only error messages are sent (to
  195.                stderr).
  196.  
  197.      s         Enables statistics-mode. Displays all kinds of funky
  198.                information to the screen while performing the
  199.                conversion. This will allow you to make good choices for
  200.                what to set different options to. I better give a short
  201.                description of what all of this information is..
  202.                "Ticks to quantize" is the amount of MIDI ticks that
  203.                every note will be rounded to (it defaults to a 16th
  204.                note). The amount of ticks representing a particular
  205.                time-value will change from MIDI file to MIDI file.
  206.                "Number of tracks" is the number of tracks in a (format
  207.                1) MIDI file. You will need this many files open plus one
  208.                to read the MIDI file.
  209.                "Maximum quantize error" is the biggest MIDI note length
  210.                rounding error. By relating this to "Ticks to quantize"
  211.                you get an idea of how much notes will be off-timing.
  212.                "Number of times it occurred" is obvious.
  213.                "Number of times quantize error > 2 occurred" helps you
  214.                get some perspective for the previous item, and how
  215.                accurate the conversion was overall.
  216.                "Number of pitch conversions out of range" is how often a
  217.                pitch was encountered that was beyond the playable range
  218.                for a sample (use the "extend" option in ptmid.cfg to
  219.                decrease these errors - if you haven't already).
  220.                "Number of dropped notes" shows how often a note was cut
  221.                while being written to the Tracker file. It should stay
  222.                pretty constant for any particular tune (even if you vary
  223.                the quantize fraction), but by adding more channels you
  224.                will decrease it.
  225.  
  226. EXAMPLES
  227.  
  228.      prompt> ptmid -s -f32t jazz3 jazztune
  229.  
  230.      ptmid ver 0.3: Converting 'jazz3.mid' to 'jazztune.mtm'
  231.       Ticks to quantize: 16
  232.       Number of tracks: 11
  233.       Maximum quantize error: 8
  234.       Number of times it occurred: 145
  235.       Number of times quantize error > 2 occurred: 501
  236.      Analyzing..
  237.       Number of pitch conversions out of range: 0
  238.      Writing..
  239.       Number of dropped notes: 0
  240.      Writing 10 samples: ..........
  241.      Done.
  242.  
  243.      prompt> ptmid test
  244.  
  245.      ptmid ver 0.3: Converting 'test.mid' to 'test.mod'
  246.      Analyzing..
  247.      Writing..
  248.      Writing 2 samples: ..
  249.      Done.
  250.  
  251.  
  252. DIAGNOSTICS
  253.  
  254.      The following errors terminate immediately and return an exit code
  255.      of 1 (disclaimer: error messages may not exactly match those
  256.      shown below).
  257.  
  258.      Cannot find config file: xxxx
  259.  
  260.           Either ptmid.cfg cannot be found (eg. not in current
  261.           directory) or the file specified with the option -c has been
  262.           incorrectly given.
  263.  
  264.      Error in config file: line xx
  265.  
  266.           Something is wrong with the config file on that line. Check
  267.           the above formats for options.
  268.  
  269.      No default instrument defined in config file
  270.  
  271.           Make sure there is a "def" option in the config file.
  272.  
  273.      No sample definitions found in config file
  274.  
  275.           Likewise, make sure there is a "sample" option.
  276.  
  277.      Invalid quantize fraction - using default
  278.  
  279.           You have incorrectly specified the fraction in the -f option.
  280.           Make sure it is of a similar form to: 4, 4t, 8, 8t, etc. Ptmid
  281.           is going ahead, but using the value 16.
  282.  
  283.      Cannot access file: xxxx
  284.  
  285.           The MIDI file you have specified cannot be opened for reading.
  286.  
  287.      Not a legal MIDI file: xxxx
  288.  
  289.           There is something wrong with the MIDI file you have
  290.           specified (like it isn't one), or there is a copyright notice
  291.           in it and the NOCOPY option has been enabled (see above).
  292.  
  293.      Cannot create file: xxxx
  294.  
  295.           The Protracker file cannot be opened for writing.
  296.  
  297.      No more files can be opened
  298.  
  299.           While reading the MIDI file, Ptmid has run out of file handles
  300.           (there should be at least 1 more than the number of tracks in
  301.           the file), so if you can increase them, please do (see manual
  302.           on how to do this). The official version of Ptmid supports
  303.           upto 34 track MIDI files (which opens 38 files under MSDOS)
  304.           and won't work on larger ones - this is a bug with Turbo C.
  305.  
  306.      Cannot allocate any more memory
  307.  
  308.           Nasty. Try recompiling the sources to use a bigger memory
  309.           model, install more memory (probably make no difference),
  310.           switch to a different operating system, or wait until other
  311.           users leave. I have managed to convert MIDI files upto 80k in
  312.           size under MSDOS.
  313.  
  314.      The follow errors do not terminate immediately, though may cause
  315.      early termination, hence will return an exit code of 0.
  316.  
  317.      Warning -- Pattern limit xx reached. Aborting!
  318.  
  319.           Try using a smaller number of the quantize fraction. A Tracker
  320.           file will be created anyway, so at least you will have
  321.           something.
  322.  
  323. HISTORY
  324.  
  325.      0.1
  326.           Initial release. Spread far and wide, and a couple of people
  327.           were quite impressed.
  328.  
  329.      0.2
  330.           Increase of maximum number of open files from 15 to 35
  331.           (involved patching Turbo C 2.0). Statistics mode added. Never
  332.           officially released.
  333.  
  334.      0.3
  335.           Removed bug with MIDI Sysex events. Removed bug where odd (as
  336.           apart from even) length .SMP files weren't processed properly.
  337.           Percussion samples now played for 1/8th note (rather than the
  338.           length in the MIDI file). .VOC and .WAV files now supported.
  339.           Pitch value added to end of percussion allocations. Pitch
  340.           value for percussion samples after "sample" tag now makes
  341.           sense. Ditto (quote) abbreviation added to config file.
  342.           "spath", "rgmode", "modfmt" and "maxchan" tags added to config
  343.           file, while "ptchan", "patmax" and "formid" are removed. Tags
  344.           for .mod files corresponding to channel sizes are:
  345.                TDZ1, TDZ2, TDZ3, M!K!, 5CHN, 6CHN, 7CHN, 8CHN, 9CHN,
  346.                10CH, 11CH, 12CH, 13CH, 14CH, 15CH, 16CH, ... 32CH.
  347.           Oh.. and MTM files now supported (he waits for applause?).
  348.  
  349. Andrew Scott
  350. INTERNET:ascott@tartarus.uwa.edu.au
  351.